Skip to content

infra: add sync:ii-spec script, port II spec commits, and sync vc-spec#249

Merged
raymondk merged 14 commits into
mainfrom
infra/sync-ii-spec
May 13, 2026
Merged

infra: add sync:ii-spec script, port II spec commits, and sync vc-spec#249
raymondk merged 14 commits into
mainfrom
infra/sync-ii-spec

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 12, 2026

Summary

  • Adds scripts/sync-ii-spec.mjs — a deterministic sync script that transforms upstream specs from dfinity/internet-identity into reference pages; same pattern as sync-motoko.sh
  • Syncs two specs in one pass:
    • docs/ii-spec.mdxdocs/references/internet-identity-spec.md: strip MDX imports, remove H1, rewrite 8 absolute internetcomputer.org link patterns to relative paths, inline the Candid .did file in place of <CodeBlock>, inject frontmatter, append link-adaptation log
    • docs/vc-spec.mddocs/references/verifiable-credentials-spec.md: remove H1, rewrite 5 stale portal links to relative internal paths, inject frontmatter, append link-adaptation log; upstream fix tracked in dfinity/internet-identity#3889
  • Pins .sources/internetidentity to release-2026-05-08 (f6cf858) — switches from main-tracking to release-tracking; spec changes are only live once the canister is deployed
  • Adds internetidentity to .sources/VERSIONS alongside other release-pinned submodules
  • Adds "sync:ii-spec": "./scripts/sync-ii-spec.mjs" to package.json
  • Adds .github/workflows/sync-ii-spec.yml — runs weekly on Tuesday and on workflow_dispatch; finds the latest release-YYYY-MM-DD tag, filters for changes to ii-spec.mdx, vc-spec.md, or internet_identity.did, and opens a PR (with VERSIONS update) only if relevant files changed
  • Adds verifiable-credentials-spec to the sidebar and reference index
  • Updates the VC guide's "Next steps" to link to the new reference page instead of the raw GitHub file
  • Updates AGENTS.md: documents both output files, vcLinkMap, release-based pinning strategy, and the "only bump if synced docs changed" policy
  • Fixes scripts/validate.js: checkForbiddenPatterns now skips code blocks (same as checkEmdash), preventing false positives on URLs inside Candid code comments

Sync recommendation

sync from dfinity/internet-identity — docs/ii-spec.mdx, docs/vc-spec.md, src/internet_identity/internet_identity.did

Adds scripts/sync-ii-spec.mjs — a deterministic 1:1 sync script that
transforms docs/ii-spec.mdx from dfinity/internet-identity into
docs/references/internet-identity-spec.md. Applies the same pattern as
sync-motoko: strip MDX imports, remove H1, inline the Candid .did file,
rewrite 8 absolute link patterns to relative paths, inject frontmatter.

Bumps .sources/internetidentity to af980848..74ad617 (16 commits) and
regenerates internet-identity-spec.md from the new pin.

Updates AGENTS.md: internetidentity row now says to run npm run sync:ii-spec
instead of manually applying patches; link-adaptation note updated to match.
@marc0olo marc0olo requested a review from a team as a code owner May 12, 2026 16:21
marc0olo added 11 commits May 12, 2026 18:26
…cope

Three corrections to the sync script:
- Add m flag to H1 regex so it matches after leading blank lines from import stripping
- Move Candid inlining after link rewriting so .did code comments are not rewritten
- Exclude code blocks from the remaining-links check (prose only)
- Restore sidebar order: 14 to match previous value
FETCH_HEAD is a file that could theoretically be overwritten between
steps if another fetch runs. Using the hash saved to step outputs is
safer and more explicit.
checkEmdash already tracks inFence state to skip code blocks.
checkForbiddenPatterns was missing the same logic, causing false
positives on URLs inside Candid/code block comments.
…nline

Consistent with ic.did / http-gateway.did: copy internet_identity.did to
public/references/internet-identity.did and replace the <CodeBlock> inline
with a prose download link. Reduces internet-identity-spec.md from 2075
to 736 lines. Workflow updated to stage the .did file.
Site uses remarkPlantUML; Mermaid blocks render as raw text. The sync
script now converts sequenceDiagram blocks to PlantUML automatically.
Conversion rules: participant alias/name flipped and quoted, <br>
becomes \n, sequenceDiagram keyword stripped, wrapped in @startuml/@enduml.
Adds a validation check that exits non-zero if any mermaid blocks remain
after conversion (catches unsupported diagram types added upstream).
…rand skin

The plugin only injects the SKIN when content does not already start with
@startuml. Other diagrams in the docs omit the wrapper and let the plugin
add it. Converted diagrams now follow the same pattern.
…dentials-spec.md

Extends the sync script to also produce a normative reference page from
.sources/internetidentity/docs/vc-spec.md. Rewrites 5 stale portal links
at sync time; upstream fix tracked in dfinity/internet-identity#3889.

The ii-spec link to vc-spec.md now resolves to the reference page instead
of the implementation guide. The guide's "Next steps" section updated
to link to the new reference page rather than the raw GitHub file.
- Submodule table: add docs/vc-spec.md as a synced source
- Extra checks row: document vcLinkMap, clarify the "only bump if synced
  docs changed" policy, and note the workflow skips unrelated code bumps
- Link adaptation section: cover verifiable-credentials-spec.md and note
  that the vc-spec rewrites become harmless once dfinity/internet-identity#3889 is resolved
- Workflow: add docs/vc-spec.md to the changed-files filter, stage
  verifiable-credentials-spec.md in the commit step, and update PR body
@marc0olo marc0olo changed the title infra: add sync:ii-spec script and port 16 upstream spec commits infra: add sync:ii-spec script, port II spec commits, and sync vc-spec May 13, 2026
marc0olo added 2 commits May 13, 2026 14:35
Switches the internetidentity submodule from main-tracking to
release-tracking. Spec changes are only live once the canister is
deployed at a release, so pinning to main could expose unreleased
changes in docs.

- Pins submodule to release-2026-05-08 (f6cf858), reverting an
  unreleased internet_identity.did change
- Updates VERSIONS to record the current release
- Workflow now finds the latest release-YYYY-MM-DD tag (not main),
  uses tag name in branch/commit/PR title, and auto-updates VERSIONS
- AGENTS.md: updates pinning strategy description and extra checks row
@raymondk raymondk merged commit ecfef03 into main May 13, 2026
8 checks passed
@raymondk raymondk deleted the infra/sync-ii-spec branch May 13, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants